package org.example.service;

import org.example.entity.AccessStatistics;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 访问统计服务接口
 * 
 * @author Your Name
 * @since 2024-07-01
 */
public interface AccessStatisticsService {
    
    /**
     * 记录访问统计
     * 
     * @param shortCode 短链接编码
     * @param ipAddress 访问者IP
     * @param userAgent 用户代理
     * @param referer 来源页面
     */
    void recordAccess(String shortCode, String ipAddress, String userAgent, String referer);
    
    /**
     * 获取短链接的访问统计
     * 
     * @param shortCode 短链接编码
     * @return 访问统计列表
     */
    List<AccessStatistics> getAccessStatistics(String shortCode);
    
    /**
     * 获取指定时间范围内的访问统计
     * 
     * @param shortCode 短链接编码
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 访问统计列表
     */
    List<AccessStatistics> getAccessStatisticsByTimeRange(String shortCode, LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 获取短链接的总访问次数
     * 
     * @param shortCode 短链接编码
     * @return 总访问次数
     */
    int getTotalAccessCount(String shortCode);
    
    /**
     * 获取指定时间范围内的访问次数
     * 
     * @param shortCode 短链接编码
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 访问次数
     */
    int getAccessCountByTimeRange(String shortCode, LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 清理过期数据
     * 
     * @param expireDays 过期天数
     */
    void cleanExpiredData(int expireDays);
    
    /**
     * 获取短链接的日访问量
     * 
     * @param shortCode 短链接编码
     * @param date 日期，格式：yyyy-MM-dd
     * @return 日访问量
     */
    int getDailyAccessCount(String shortCode, String date);
    
    /**
     * 获取短链接的小时访问量
     * 
     * @param shortCode 短链接编码
     * @param hour 小时，格式：yyyy-MM-dd-HH
     * @return 小时访问量
     */
    int getHourlyAccessCount(String shortCode, String hour);
    
    /**
     * 获取短链接的独立IP数量
     * 
     * @param shortCode 短链接编码
     * @param date 日期，格式：yyyy-MM-dd
     * @return 独立IP数量
     */
    long getUniqueIpCount(String shortCode, String date);
    
    /**
     * 获取短链接的访问统计概览
     * 
     * @param shortCode 短链接编码
     * @return 统计概览字符串
     */
    String getAccessStatisticsOverview(String shortCode);
    
    /**
     * 批量保存访问统计数据到数据库
     * 将Redis中的统计数据批量同步到数据库
     */
    void batchSaveToDatabase();
}
